/*--
 * ICommand.cs: Interface for command objects.
 *--
 * For more information, please visit the Metashell Project site:
 *   http://code.google.com/p/metashell/
 *--
 * (c) 2006 Christopher E. Granade.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; exactly version 2
 * of the License applies to this software.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

using System;
using System.Xml;

namespace Metashell.Core {
	
	/// <summary>
	/// Structure representing a pairing of an XML document and a short string
	/// specifiying its format
	/// (using one of the members of <see cref="MetadocFormats" />).
	/// </summary>
	public struct Metadoc {
		
		/// <summary>
		/// String specifying the format of the Metadoc. See
		/// <see cref="MetadocFormats" /> for possible values.
		/// </summary>
		public string format;
		
		/// The actual content of the Metadoc.
		public XmlDocument data;
		
	}

	/// <summary>
	/// Interface to be inhereted by any commands used in the Metashell system.
	/// </summary>
	public interface ICommand {
		
		#region Properties
		
			/// <summary>
			/// Name to be used on the command-line by the user.
			/// </summary>
			string name {get;}
			
		#endregion
		
		#region Methods
		
			/// <summary>
			/// Runs the command.
			/// </summary>
			/// <param name="parameters">The part of the command invocation following
			/// 	the command name. For example, if <c>ls</c> was run with
			/// 	<c>ls -l /var/tmp</c>, <c>parameters</c> would be set to
			/// 	<c>-l /var/tmp</c>.</param>
			/// <param name="indoc">The results of the previous command on the
			///		current command line, or XML.NullDocument if this command
			///     is first.</param>
			/// <param name="outdoc">The results of this command. If this command does
			/// 	not return XML results, then this parameter must be set to
			///		XML.NullDocument within the body of the function.</param>
			void Run(
				string parameters,
				Metadoc indoc,
				out Metadoc outdoc
			);
			
			/// <summary>
			/// Registers which instance of the Metashell core is being used.
			/// </summary>
			void RegisterCore(Core core);
			
		#endregion
	
	}
	
	
}
